Yet another healthApp

One day, one person, one project

AI-Powered Health & Nutrition Tracking

Features · Quick Start · Documentation · 中文文档

---

Track nutrition, exercise, and wellness with AI-powered personalized insights

---

⚠️ Security Notice

Important: Please ensure you're using the latest security-patched versions:

• Next.js: 16.0.10+ or 16.1.x (CVE-2025-66478)
• React: 19.2.3+ (CVE-2025-55182, CVE-2025-55183, CVE-2025-55184)

Run npm audit regularly and keep dependencies updated.

---

✨ Features

Feature	Description
🍽️ Smart Food Logging	AI-powered food recognition with automatic nutrition calculation
⚖️ Body Metrics	Track weight, BMI, body fat percentage, and fitness progress
🏋️ Workout Tracking	Log exercises with duration, calories burned, and intensity
🔬 Ingredient Analysis	Scan and analyze food ingredients for health insights
📊 Analytics Dashboard	Visualize trends with interactive charts and statistics
🤖 AI Health Assistant	Get personalized nutrition and fitness recommendations
📱 Mobile-First Design	Responsive UI optimized for all devices
🔐 Secure Authentication	JWT-based auth with token refresh mechanism

---

🛠️ Tech Stack

Frontend

Technology	Version	Description
Next.js	16.1.x	React framework with App Router & Turbopack
React	19.2.x	UI library with Actions & Server Components
TailwindCSS	4.x	Utility-first CSS (CSS-first config)
Zustand	5.x	Lightweight state management
TanStack Query	5.x	Server state management
Radix UI	latest	Accessible UI primitives

Backend

Technology	Version	Description
FastAPI	0.115+	High-performance Python web framework
PostgreSQL	15+	Relational database
SQLAlchemy	2.0	Async ORM
Alembic	1.14+	Database migrations
Pydantic	2.x	Data validation
OpenAI API	GPT-4	AI integration

---

🚀 Quick Start

Prerequisites

Tool	Version	Installation
Python	3.11+	python.org
Node.js	20+	nodejs.org
pnpm	9+	npm install -g pnpm
uv	Latest	curl -LsSf <https://astral.sh/uv/install.sh> | sh
Docker	Latest	docker.com

One-Command Setup

# Clone and enter directory
git clone <https://github.com/staruhub/Healthapp.git> && cd Healthapp

# Start database
docker-compose up -d

# Terminal 1: Backend
cd backend && cp .env.example .env
uv sync && uv run alembic upgrade head
uv run uvicorn app.main:app --reload --port 8001

# Terminal 2: Frontend
cd frontend && echo "NEXT_PUBLIC_API_URL=http://localhost:8001" > .env.local
pnpm install && pnpm dev

🎉 Access the app:

• 🌐 Frontend: http://localhost:3000
• 📚 API Docs: http://localhost:8001/docs

---

⚙️ Configuration

Backend .env

# Database
DATABASE_URL=postgresql+asyncpg://healthapp:healthapp_dev_2024@localhost:5432/healthapp_db

# Security (REQUIRED: openssl rand -hex 32)
SECRET_KEY=your-super-secret-key-here

# AI Mode: "mock" (dev) | "real" (prod)
AI_MODE=mock
OPENAI_API_KEY=sk-...  # Required when AI_MODE=real

# CORS
CORS_ORIGINS=["<http://localhost:3000>"]

Frontend .env.local

NEXT_PUBLIC_API_URL=http://localhost:8001
NEXT_PUBLIC_AI_MODE=mock

---

📚 API Documentation

Endpoints Overview

Method	Endpoint	Description
POST	/api/v1/auth/register	User registration
POST	/api/v1/auth/login	User login
POST	/api/v1/auth/refresh	Refresh access token
GET	/api/v1/food/logs	Get food logs
POST	/api/v1/food/parse	AI food parsing
GET	/api/v1/body/logs	Get body metrics
GET	/api/v1/dashboard/summary	Dashboard data
POST	/api/v1/chat	AI chat assistant

Interactive documentation available at:

• Swagger UI: GET /docs
• ReDoc: GET /redoc
• Health Check: GET /health

---

📁 Project Structure

Healthapp/
├── backend/                    # FastAPI Backend
│   ├── app/
│   │   ├── api/v1/            # API Routes
│   │   │   ├── auth.py        # Authentication
│   │   │   ├── food.py        # Food logging
│   │   │   ├── body.py        # Body metrics
│   │   │   ├── workout.py     # Workout tracking
│   │   │   ├── dashboard.py   # Dashboard
│   │   │   ├── chat.py        # AI chat
│   │   │   └── ingredient.py  # Ingredient analysis
│   │   ├── models/            # SQLAlchemy Models
│   │   ├── schemas/           # Pydantic Schemas
│   │   ├── services/ai/       # AI Service Layer
│   │   └── utils/             # Utilities
│   ├── alembic/               # Database Migrations
│   └── pyproject.toml
│
├── frontend/                   # Next.js Frontend
│   ├── app/                   # App Router Pages
│   │   ├── (auth)/            # Auth pages
│   │   └── (main)/            # Main app pages
│   ├── components/            # React Components
│   │   ├── ui/                # Base UI
│   │   ├── chat/              # Chat components
│   │   └── onboarding/        # Onboarding flow
│   ├── hooks/                 # Custom React Hooks
│   ├── store/                 # Zustand State
│   ├── lib/                   # Utilities
│   └── types/                 # TypeScript Types
│
├── openspec/                  # Project Specifications
├── docker-compose.yml
└── README.md

---

🔧 Troubleshooting

Database Connection Failed

# Check container status
docker ps | grep postgres

# Restart container
docker-compose restart

# View logs
docker-compose logs postgres

Port Already in Use

# Find process
lsof -i :8001

# Kill process
kill -9 <PID>

# Or use different port
uv run uvicorn app.main:app --reload --port 8002

Frontend Cannot Connect to Backend

1. Verify backend: curl <http://localhost:8001/health>
2. Check NEXT_PUBLIC_API_URL in .env.local
3. Verify CORS settings in backend .env
4. Clear browser cache and restart

Token/Authentication Issues

# Clear stored tokens in browser
localStorage.removeItem('auth-storage')
# Then refresh the page

---

❓ FAQ

What is AI_MODE?

• mock: Returns pre-defined responses (no API costs, for development)
• real: Uses OpenAI GPT-4 API (requires OPENAI_API_KEY)

How to reset the database?

dropdb healthapp_db && createdb healthapp_db
cd backend && uv run alembic upgrade head

How to generate a secure SECRET_KEY?

openssl rand -hex 32

---

🤝 Contributing

1. Fork the repository
2. Create feature branch: git checkout -b feature/AmazingFeature
3. Commit changes: git commit -m 'feat: add amazing feature'
4. Push to branch: git push origin feature/AmazingFeature
5. Open Pull Request

Commit Convention

Type	Description
feat	New feature
fix	Bug fix
docs	Documentation
style	Formatting
refactor	Code refactoring
test	Adding tests
chore	Maintenance

---

📄 License

This project is licensed under the MIT License - see LICENSE for details.

---

🇨🇳 中文文档

点击展开中文说明

功能特性

• 🍽️ 智能食物记录 - AI 驱动的食物识别，自动计算营养成分
• ⚖️ 身体指标追踪 - 追踪体重、BMI、体脂率和健身进度
• 🏋️ 运动追踪 - 记录运动时长、消耗卡路里和运动强度
• 🔬 成分分析 - 扫描分析食品配料，提供健康洞察
• 📊 数据仪表盘 - 交互式图表可视化健康趋势
• 🤖 AI 健康助手 - 获取个性化营养和健身建议

快速开始

# 克隆仓库
git clone <https://github.com/staruhub/Healthapp.git> && cd Healthapp

# 启动数据库
docker-compose up -d

# 启动后端
cd backend && cp .env.example .env
uv sync && uv run alembic upgrade head
uv run uvicorn app.main:app --reload --port 8001

# 启动前端（新终端）
cd frontend && echo "NEXT_PUBLIC_API_URL=http://localhost:8001" > .env.local
pnpm install && pnpm dev

环境要求

依赖	版本	安装方式
Python	3.11+	python.org
Node.js	20+	nodejs.org
pnpm	9+	npm install -g pnpm
uv	最新版	curl -LsSf <https://astral.sh/uv/install.sh> | sh
Docker	最新版	docker.com

---

staruhub

⭐ Star this repo if you find it helpful! ⭐